﻿/**
 * @file std_mdebug.c
 * Copyright (c) 2019 Gaaagaa. All rights reserved.
 * 
 * @author  : Gaaagaa
 * @date    : 2019-09-09
 * @version : 1.0.0.0
 * @brief   : 用于调试操作时，记录内存分配情况的相关操作接口。
 */

/**
 * The MIT License (MIT)
 * Copyright (c) Gaaagaa. All rights reserved.
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
 * of the Software, and to permit persons to whom the Software is furnished to do
 * so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

#ifndef __STD_MDEBUG_H__
#define __STD_MDEBUG_H__

#include "std_comm.h"

////////////////////////////////////////////////////////////////////////////////

#ifdef __cplusplus
extern "C"
{
#endif // __cplusplus

////////////////////////////////////////////////////////////////////////////////

//====================================================================

// 
// xstd_mdebug_t 的相关数据定义
// 

#define XMDB_FALSE           XSTD_FALSE
#define XMDB_TRUE            XSTD_TRUE
#define XMDB_NULL            XSTD_NULL

typedef xstd_void_t          xmdb_void_t;
typedef xstd_bool_t          xmdb_bool_t;
typedef xstd_size_t          xmdb_size_t;
typedef xstd_mptr_t          xmdb_mptr_t;

/** 统计内存分配的工作对象 的指针类型 */
typedef struct xstd_mdebug_t * xmdb_this_t;

//====================================================================

// 
// xstd_mdebug_t 的相关操作接口
// 

/**********************************************************/
/**
 * @brief 创建 xstd_mdebug_t 对象。
 */
xmdb_this_t std_mdebug_create(void);

/**********************************************************/
/**
 * @brief 销毁 xstd_mdebug_t 对象。
 */
xmdb_void_t std_mdebug_destroy(xmdb_this_t xmdb_this);

/**********************************************************/
/**
 * @brief 当前 xstd_mdebug_t 对象所统计分配到的内存大小。
 */
xmdb_size_t std_mdebug_count(xmdb_this_t xmdb_this);

/**********************************************************/
/**
 * @brief 当前 xstd_mdebug_t 对象所统计分配内存块的数量。
 */
xmdb_size_t std_mdebug_size(xmdb_this_t xmdb_this);

/**********************************************************/
/**
 * @brief 从 xstd_mdebug_t 对象中获取所记录内存块的大小。
 * 
 * @param [in,out] xmdb_this : xstd_mdebug_t 对象。
 * @param [in    ] xmdb_mptr : 所记录的内存块。
 * 
 * @return xmdb_size_t : 
 * 所记录内存块的大小。为 0 时，表示其未找到记录的信息。
 */
xmdb_size_t std_mdebug_msize(
                xmdb_this_t xmdb_this,
                xmdb_mptr_t xmdb_mptr);

/**********************************************************/
/**
 * @brief 将新分配的内存信息，记录到 xstd_mdebug_t 对象中。
 * 
 * @param [in,out] xmdb_this : xstd_mdebug_t 对象。
 * @param [in    ] xmdb_mptr : 新分配的内存块。
 * @param [in    ] xmdb_size : 内存块大小。
 * 
 * @return xmdb_bool_t : 操作是否成功。
 */
xmdb_bool_t std_mdebug_record(
                xmdb_this_t xmdb_this,
                xmdb_mptr_t xmdb_mptr,
                xmdb_size_t xmdb_size);

/**********************************************************/
/**
 * @brief 将待释放的内存块，从 xstd_mdebug_t 对象中删除对应的记录信息。
 * 
 * @param [in,out] xmdb_this : xstd_mdebug_t 对象。
 * @param [in    ] xmdb_mptr : 待释放的内存块。
 * 
 * @return xmdb_bool_t : 操作是否成功。
 */
xmdb_bool_t std_mdebug_remove(
                xmdb_this_t xmdb_this,
                xmdb_mptr_t xmdb_mptr);

////////////////////////////////////////////////////////////////////////////////

#ifdef __cplusplus
}; // extern "C"
#endif // __cplusplus

////////////////////////////////////////////////////////////////////////////////

#endif // __STD_MDEBUG_H__

